home *** CD-ROM | disk | FTP | other *** search
/ Disc to the Future 2 / Disc to the Future Part II Programmer's Reference (Wayzata Technology)(6013)(1992).bin / MAC / OTHERCST / HARVEST_ / README.TEX (.txt) < prev   
LaTeX Document  |  1991-11-24  |  21KB  |  356 lines
  1. Release Notes
  2. Harvest C, Shareware version
  3. Release 1.1b2* 
  4. 24 November 1991
  5. Copyright 1991 Eric W. Sink
  6. All Rights Reserved.
  7. Harvest C is a shareware C compiler for the Macintosh.  An integrated development 
  8. environment, Harvest C is intended to be compatible with the MPW C compiler.  Harvest 
  9. C compiles (almost) all the same extensions to ANSI C which are supported by MPW C. 
  10. Harvest C also generates object files which are compatible with MPW.
  11. NOTICE
  12. Throughout this notice, the "SOFTWARE" refers to this version and only this version of Harvest C, 
  13. (including all accompanying documentation, notices, source files, executables, and release notes)  and no other 
  14. releases or products.  The following statements reflect the legal conditions of the use of this SOFTWARE.  If the 
  15. terms expressed below are unacceptable to you, then you should not use the SOFTWARE.
  16. 1. The SOFTWARE is Copyright 1991 Eric W. Sink, All Rights Reserved.  Harvest C is NOT public domain.
  17. 2. You are explicitly granted the right to use and distribute the SOFTWARE freely and publicly, as long as all 
  18. copyrights, notices, release notes, documentation, source files and executables are included and unchanged from 
  19. the original release made by the author.  You may not distribute modified copies of the SOFTWARE.
  20. 3. You may not falsely represent the author or copyright holder of the SOFTWARE, either by omission or 
  21. misrepresentation.  The author of this SOFTWARE is Eric W. Sink.  Currently the copyright holder is also Eric W. 
  22. Sink.
  23. 4. The SOFTWARE is referred to as "shareware".  Because the term "shareware" does not have a strict legal 
  24. definition, the following clarifications make the terms more specific :
  25.    a. You may register yourself (and are encouraged to do so) as a user of the SOFTWARE, by sending a fee of US 
  26. $25 to :
  27.         Eric W. Sink
  28.         1014 Pomona Drive
  29.         Champaign, Illinois  61821
  30.    b. You are under no legal obligation to register.  In general, it is recommended that you register and pay for any 
  31. shareware which you use.  This notice is merely intended to make the legal aspect of shareware registration more 
  32. specific for this SOFTWARE.
  33. 5. The SOFTWARE is provided with absolutely NO WARRANTY, under any conditions.  In no case will the author, 
  34. copyright holder, or any distributor be in any way liable for any damages or difficulties of any kind, either directly 
  35. or indirectly caused by any kind of use of this SOFTWARE.  The author, copyright holder and/or distributor of this 
  36. SOFTWARE make no legal guarantees with respect to the usability of this SOFTWARE, support of the 
  37. SOFTWARE, or future releases of the SOFTWARE.
  38. ---------- End of NOTICE ----------
  39. FUTURE DIRECTIONS
  40. This shareware version of Harvest C is being released to fill a perceived need for a freely 
  41. distributable C compiler for the Macintosh.  I intend to maintain it, and make subsequent 
  42. releases with bug fixes and new features.  It is my intent to offer a commercially available 
  43. version in the future.  The differences between that commercial version and the shareware 
  44. version have not been chosen, but it is my intent to maintain both versions.  The shareware 
  45. version will continue, and will aim to be a usable C development environment for 
  46. Macintosh users.  The following features are under consideration.  Some of them are 
  47. already implemented.  Some of them will find their way into the shareware release.  Some 
  48. will be available only in the commercial version.
  49.  68020, 68881 code generation
  50.  support for > 32k of global data
  51.  precompiled headers
  52.  SADE support
  53.  optional 16/32 bit ints
  54.  inline assembler
  55.  more complete documentation
  56.  increased speed
  57.  reporting of software metrics
  58.  support for object oriented programming
  59.  full source code to the compiler included
  60.  better code generation
  61.  better linking
  62.  full System 7 friendliness
  63. REGISTRATION
  64. You are encouraged to register yourself as a user, as described above.  
  65. Registered users will receive a discount on purchase of the commercial 
  66. version when it is released.  In addition, registered users will obtain 
  67. my attention much faster with respect to questions, fixes, desired 
  68. features and the like.  You may register yourself by supplying the 
  69. following information :
  70. Name:
  71. Address (city, state, zip, and country):
  72. Phone (optional):
  73. email address (if you have one):
  74. Age (optional):
  75. Suggestions for improvements:
  76. Enclose a check for US $25 to :
  77.     Eric W. Sink
  78.     1014 Pomona Drive
  79.     Champaign, Illinois  61821
  80. I will acknowledge all registrations.
  81. CONTACTS
  82. You are encouraged to contact me with any questions, comments, suggestions 
  83. or complaints.  You may reach me by electronic mail (USENET,Internet) at
  84. e-sink@uiuc.edu
  85. or by US mail at
  86. Eric W. Sink
  87. 1014 Pomona Drive
  88. Champaign, Illinois  61821
  89. I am not currently on AppleLink or CompuServe.
  90. USING HARVEST C
  91. Harvest C includes a built-in text editor.  This editor offers MINIMAL functionality, and is 
  92. not intended to be used as a principal programmer's editor.  The Harvest C editor does not 
  93. support, tabs, undo, multiple fonts, searching, macros, or files longer than 32000 
  94. characters.  (For general purpose editing, I recommend the use of Alpha, an excellent 
  95. shareware programmer's editor, widely available at ftp sites.)  In any case, you may use 
  96. the text editor in the normal way, in conjunction with the File and Edit menus.
  97. The Options menu allows control over some of the features of Harvest C.  Some of the 
  98. options are not enabled in the shareware version.  Harvest C stores its configuration in a 
  99. file called "Harvest C Options", in the System Folder.  It is necessary to inform Harvest C 
  100. of the locations of your include files, and libraries (see below).  You may specify these 
  101. using the entries under the Options menu.  Harvest C maintains the notion of an 
  102. "Application directory".  This is the directory in which you do most of your work.  This 
  103. may be set as an option as well.  You may (and should) save these choices as the defaults 
  104. by using the Save Defaults entry.  Harvest C reads the "Harvest C Options" file from 
  105. the System Folder when the application is opened.  If it has trouble reading the file, it 
  106. initializes all options to a set of reasonable defaults, and beeps.  This beep is to let you 
  107. know that the current option defaults are not yours, and that you should select the defaults 
  108. you prefer and save them.  Harvest C should beep the first time you run it.
  109. The Options menu has three hierarchical menus which allow a number of different 
  110. settings.  The most important for the shareware version is the Warnings menu.  This 
  111. menu allows you to turn each of the various warnings on or off.  A check mark appears 
  112. next to the warnings which are active.
  113. The Project menu allows compilation.  You may compile a single file using the 
  114. Compile entry.  Execution of a Harvest C build script is done with the Build entry.  
  115. User specified linking can be accomplished with the Link entry.
  116. Compile...
  117. This option simply allows you to compile a single file.  Harvest C presents a file dialog, 
  118. asking you to specify which file you wish to compile.  The corresponding object file is 
  119. created, and user information is displayed in a new text window.
  120. Build...
  121. Build scripts are the equivalent of Makefiles in MPW, and Project files in Think C.  A build 
  122. script describes an entire project by listing the files and libraries which are to be included in 
  123. the project.  Harvest C build scripts are very flexible, easily allowing any combination of 
  124. compiler options for any file or set of files.  Upon selecting this option, Harvest C presents 
  125. a file dialog, asking you to specify a build script.  You must create your build script by 
  126. hand, but fear not, it is not difficult, and a future version will have the ability to create it for 
  127. The Build... menu item does a full rebuild of the program specified.  The Make... menu 
  128. item is identical, except that it rebuilds only that which is necessary, based on the 
  129. modification dates of the files.  For example, say that your build script contains 5 source 
  130. files, and you build your program.  Then, you modify one source file.  Issuing the 
  131. Make... command here will recompile only that source file.  Selecting the Build... 
  132. command will recompile all 5 source files.  Both commands require that the program be 
  133. relinked.
  134. Format of Build files
  135. Each line of a build file may contain zero or more options, and zero or more filenames.  
  136. Filenames are assumed to be things which should be linked into the final application.  
  137. Filenames ending in '.c' are compiled.  Options which appear on the same line as one or 
  138. more filenames are in effect for only those files.  Options which appear alone (except for 
  139. preprocessor definitions) are in effect for the remainder of the build.  Options are specified 
  140. in an MPW like format.  On a given line, all characters after a cross hatch character (#) are 
  141. ignored (for commenting).  Furthermore, any blank line causes execution of the script to 
  142. cease (i.e. blank lines are not allowed in the middle of the file).  Legal options are (for the 
  143. shareware version)
  144.     -nolink    Compiles but does not link
  145.     -WonXXX    Turn warning number XXX on
  146.     -WoffXXX    Turn warning number XXX off
  147.     -progress    Turns progress reporting on
  148.     -signedchar    Toggles the sign of char types
  149.     -w        No warnings
  150.     -U$$$$    #undefs $$$$
  151.     -D$$$$=@@    #define $$$$ @@
  152.     -o name    Sets output file name (no spaces allowed)
  153.     -c ????    Sets output file creator signature (no quotes, i.e. no spaces)
  154. When executing a build script, Harvest C looks in the standard application directory for C 
  155. source files needing compilation.  For object files needed for the link, Harvest C looks first 
  156. in the application directory, then in the standard library directory.
  157. Link...
  158. Using this option you may link any group of files you like.  Harvest C displays a dialog for 
  159. selection of object files for the link.  Select as many as you like, clicking the Add button 
  160. after each one.  After the last file, click the Done button.  Then Harvest C asks you (with 
  161. a dialog) for the destination of the link output (the application you will be generating).  
  162. User information from the link appears in a new text window.
  163. Warnings
  164. This version of Harvest C supports the following warnings.  Warnings appearing in bold 
  165. are turned on by default.
  166. 1        Empty expression stmt  
  167. 2        Multi-character constant
  168. 3        Redundant cast
  169. 4        Equivalence test of floating type
  170. 5        Discarded function result
  171. 6        Assignment as if conditional
  172. 7        Non-void function has no return statement
  173. 8        Constant expression as if condition
  174. 9        Comparison of pointer and integer
  175. 10        Assignment of nonequivalent type to a pointer
  176. 11        Return of nonequivalent type to a pointer
  177. 12        Pass of nonequivalent type to a pointer
  178. 13        Constant expression as switch condition
  179. 14        Constant expression as while loop condition
  180. 15        Constant expression as do-while loop condition
  181. 16        Constant expression as for loop condition
  182. 17        Switch expression not of integral type.
  183. 18        Volatile is not handled by this compiler
  184. 20        Unused variable: 
  185. 21        Dead code
  186. 22        Implicit decl : 
  187. 23        Re#definition : 
  188. 24        Possible nested comment
  189. 26        goto statement found
  190. 27        Multiple function returns
  191. 28        Empty compound statement
  192. 29        Missing function return type - default to int
  193. 30        Trigraph found
  194. 32        pascal keyword found
  195. 34        Semicolon after function body
  196. Miscellaneous
  197. It is possible to abort compilation by pressing and holding Command-period.
  198. Harvest C supports Balloon Help under System 7.
  199. Pragmas
  200. Harvest C supports two pragmas from MPW C, parameter (for use by the include files) 
  201. and segment.  In other words, it does not support once, trace, processor, 
  202. force_active, push, or pop (or any others which I missed), yet.
  203. The parameter pragma should be of no use to normal programmers.
  204. The segment pragma is used for code resource segmentation :
  205. #pragma segment Foo
  206. means that all subsequent code goes in the segment named Foo.
  207. Required Memory
  208. Harvest C likes to have a lot of memory.  This is due in part to some inefficient memory 
  209. management, and should be improved in the future.  Meanwhile, try to keep your C source 
  210. files small.  Keep in mind, that even a tiny C source file effectively becomes huge if it 
  211. #includes several standard header files.
  212. Extensions to ANSI C
  213. Harvest C attempts to be an ANSI C compiler.  The various ANSI specific features are all 
  214. supported, including but not limited to function prototypes, trigraphs, stringization, token 
  215. concatenation, string literal concatentation, and so on.
  216. Harvest C attempts to support the same extensions to ANSI C which are supported by 
  217. Apple with their MPW C compiler.  Specifically, the following features are implemented :
  218. Harvest C supports the keywords extended, pascal, and comp.  The extended 
  219. keyword is taken as synonym for long double.  The comp keyword is a 64 bit integer 
  220. data type.  Harvest C accepts comp declarations but does not currently support the comp 
  221. data type.
  222. The pascal keyword is used for defining functions with pascal calling conventions.  For 
  223. example :
  224. pascal int foo(short bar) {
  225.   return bar * 5;
  226. Harvest C may reserve the keyword asm as well.  This will be used in the future to support 
  227. inline assembly code.
  228. Harvest C supports pascal style string literals.  For example,
  229. char *s = "\pWelcome";
  230. will result in a string which begins with a length byte of 7 and is null terminated.
  231. Harvest C predefines the following preprocessor symbols for conditional compilation :
  232.     MC68000
  233.     mc68000
  234.     m68k
  235.     macintosh
  236.     applec
  237. These are essentially the same such symbols as are defined by MPW C.
  238. Enumerated types are always treated as int.  Harvest C sizes all enumerated types at the 
  239. size of an int instead of adjusting their size based on the number of member constants.
  240. Harvest C accepts but ignores the keyword volatile.
  241. Harvest C accepts register class declarations of automatic variables, and will attempt to 
  242. honor such requests.  This behavior is not guaranteed for future versions.
  243. Harvest C supports direct functions like MPW C :
  244. pascal void PenSize(short width, short height) = 0xA89B;
  245. Sizes of data types in bytes are as follows :
  246. char            1
  247. short        2
  248. int            4
  249. long            4
  250. pointers        4
  251. float        4
  252. double        8
  253. extended        10
  254. Registers D0,D1,D2,A0, and A1 are scratch registers.
  255. The total size of all global variables, static variables, string constants, and floating point 
  256. constants may not exceed 32K bytes.  Floating point constants are of type extended.
  257. Harvest C accepts multiple character constants, like 'APPL'.
  258. Interfaces & Libraries
  259. In order for your program to be linked to form an application, you must link with some 
  260. standard libraries.  These libraries allow access to Toolbox routines, handle initialization of 
  261. global variables, and things like that.  Furthermore, use of these libraries will generally 
  262. require that you use the interface (or header) files which accompany them.
  263. You must obtain Apple's headers and libraries in order to use Harvest C.  I  do not yet have 
  264. legal permission to distribute them.  They are sold from the Apple Programmers and 
  265. Developers Association, and are called "MPW Toolbox Interfaces and Libraries v. 7.0", 
  266. product number M0615LL/B, at a cost of $40.  You may reach APDA at :
  267.     APDA
  268.     Apple Computer, Inc.
  269.     20525 Mariani Avenue
  270.     Mail Stop 33G
  271.     Cupertino, CA 95014-6299
  272. You may also obtain the necessary headers and libraries by anonymous ftp from 
  273. ftp.apple.com.  You need the file cincludes-mpw3-2.hqx, in directory 
  274. /dts/mac/system7/7.0.mpw/interfaces.  This is a Binhexed, Stuffit archive 
  275. containing the header files.  In addition, you need the files clibraries.hqx and 
  276. libraries.hqx, stored in directory /dts/mac/system7/7.0.mpw/libraries.  
  277. Obtaining the files by anonymous ftp is not difficult.  You must first connect with Apple's 
  278. computer, by typing the following at the shell prompt of your UNIX system.
  279. ftp ftp.apple.com
  280. You should see something like
  281. 220 bric-a-brac.apple.com FTP server (IG Version 5.90 (from 
  282. BU, from UUNET 5.51)...
  283. Name (bric-a-brac.apple.com:yourlogin): 
  284. Enter your name as anonymous (don't misspell it), and enter your full email address as 
  285. the password.  Then change to the proper directory by typing
  286. cd /dts/mac/system7/7.0.mpw/interfaces
  287. and obtain the interfaces by entering
  288. get cincludes-mpw3-2.hqx
  289. Then, 
  290. cd /dts/mac/system7/7.0.mpw/libraries
  291. and obtain the interfaces by entering
  292. get clibraries.hqx
  293. get libraries.hqx
  294. Enter quit to terminate your ftp connection.
  295. Harvest C will not work with the MPW 3.1 headers and libraries.
  296. Sample Programs
  297. This release of Harvest C shareware comes with 2 sample programs.  Sample1 is truly 
  298. trivial.  It simply does some math calculations and beeps three times.
  299. Sample2 is still not very complex, but it does create and manage a menu, allowing the user 
  300. to quit or use desk accessories.  Sample2 has two C source files, called Sample2a.c and 
  301. Sample2b.c.  Sample2a.c is very large, and Harvest C may require a large amount of 
  302. memory to compile it.  See the problems section below for comments about hogging 
  303. memory.
  304. "I'm lost - what does all this mean ?"
  305. This informational file is not intended to be full documentation.  I have made countless 
  306. assumptions about the experience of the reader.  If you are totally lost and do not 
  307. understand the terms of this document, be advised that I am preparing better 
  308. documentation.  In addition, feel free to contact me by electronic mail if you have any 
  309. questions.  I will accept questions from anyone, but I will respond to my registered users 
  310. first.
  311. Keep in mind that even the finest documentation for this product would not be a tutorial for 
  312. the C language.  There are some good books on C available.  Better documentation would 
  313. include a list of them here.
  314. If you are a relatively experienced C user and want to know specific details about how 
  315. Harvest C handles a certain situation, the only answer I have for you now is : "It works 
  316. just like MPW C".  This is undoubtedly not always true, but it is the ideal I want to strive 
  317. for.  I have written Harvest C to be compatible with MPW in almost every way.  This does 
  318. NOT make Harvest C just as good as MPW C, just compatible.  More specifically, MPW 
  319. C is currently faster and more reliable, produces better code, handles the comp data type, 
  320. does precompilation of headers, and supports the "32 bit everything" architecture.  My goal 
  321. is to make Harvest C a highly competent system in its own right, but I do not plan on 
  322. attempting to eliminate any of existing products, which are of excellent quality.
  323. CURRENT PROBLEMS
  324. As no software is bug free, and compilers are particularly prone to problems, I will not be 
  325. so foolish as to claim that Harvest C is perfect.  I do want to hear of any problems you 
  326. may have.  Please report difficulties to me so I can make bug fixes.  I plan to make 
  327. subsequent releases to fix problems.  The following items are already known, and I plan on 
  328. correcting them :
  329. 1. The compiler is slow.
  330. 2. Documentation is poor, almost nonexistent.
  331. 3. Handling of errors is poor.
  332. 4. The editor is very poor.  I have no plans of improving this, but I do plan to integrate 
  333. Harvest C with another editor, using System 7 IAC.
  334. 5. Needs System 7 friendliness (more Balloon help and Apple Events).  Compatibility with 
  335. virtual memory or 32 bit mode is unknown.
  336. 6. Harvest C currently does not support the MPW comp data type
  337. 7.  The reliability of SANE floating point math is not fully known.  It has not been 
  338. extensively tested.  Floating point math generated for the 68881 (not available in the 
  339. shareware version) has been tested more extensively.
  340. 8.  Harvest C does not support printing text files from within the compiler application.
  341. 9.  The Harvest C Linker is not as smart as the MPW linker.  It produces bloated 
  342. applications.
  343. 10.  Harvest C is a memory hog.  The efficiency of its memory usage will be cleaned up as 
  344. the program matures.  This should speed up compilation as well.
  345. 11.  Harvest C sometimes produces code which is truly inane.  I know about it, and I am 
  346. working on it.  I certainly welcome technical suggestions from any users (many of which I 
  347. know are far wiser than I).  I don't have too much difficulty looking at the Harvest C 
  348. output and seeing obvious problems, but I still welcome your ideas.
  349. 12.  The Harvest C user interface is rather poor.  This has been pointed out to me by a 
  350. number of testers, and I have been convinced to pay more attention to improving it.  The 
  351. most glaring problem is the hierarchial warnings menu, which is really an abuse of the 
  352. menu manager.
  353. * The version number 1.1a1 indicates that this is a test version of Harvest C.  This means that this release 
  354. is considered Freeware.  No shareware registration fee is requested, but the copyright remains identical.  You 
  355. areencouraged to report any problems, and use this version at your own risk.
  356.